ACME Certificate Management

The Automatic Certificate Management Environment (ACME) modules obtain, install, renew, and revoke Transport Layer Security (TLS) certificates. They implement the client side of RFC 8555 and work with Let's Encrypt or another compatible ACME service. The modules are shared by the Barracuda App Server (BAS), Mako Server, and Xedge.

A certificate lets an HTTPS client verify the identity of your server. ACME automates obtaining and renewing that certificate. Before choosing a configuration, decide how the certificate authority (CA) will verify that your server is authorized to use its name:

Automatic DNS-01 is useful for memory-constrained embedded systems because it does not require a public inbound connection. It works with Xedge or with an application built directly from the Barracuda App Server libraries.

HTTP-01 proves control by serving a temporary file on your server. DNS-01 proves control by publishing a temporary text (TXT) record in the Domain Name System (DNS). SharkCA instead uses authenticated device enrollment and a private trust root.

Choose your entry point. On Mako Server, start with the mako.conf settings. On Xedge, use the certificate-settings interface. Those hosts create the runtime for you. To manage certificates from Lua, start with the examples below and acme/runtime. The DNS adapter, certificate manager, and protocol engine are covered later for custom integrations.

Start with staging for public certificates. The examples select the Let's Encrypt staging service with production=false. Staging certificates are not trusted by browsers, but staging lets you test without consuming production rate limits. Change the setting to true only after the complete flow works. SharkCA uses its own private CA and has no staging selector.

Start with a Working Configuration

The four examples use the same runtime on Mako Server and Xedge. The runtime selects the host's writable I/O automatically and installs certificates in the standard ba.slcon and ba.slcon6 HTTPS listeners. An application that embeds the BAS library directly must supply an io option and the install callback described under Runtime.create(). You can also supply these options on Mako or Xedge when using different storage or HTTPS listeners.

Before running an example, make sure networking, the system clock, a trusted HTTPS client, and private writable storage are ready. Replace the sample domain and email with your own values. See runtime and build requirements for custom BAS hosts.

The notify(code, msg) function receives a numeric lifecycle code and, for two events, an optional message string. The startup callback reports whether certificate management started successfully. Do not log private keys, SharkTrust credentials, zone secrets, proof values, or authorization headers.

HTTP-01 Example

Use the same configuration table on Mako, Xedge, or a custom BAS host. Omitting challenge selects HTTP-01. The certificate authority must reach the device on public TCP port 80.

local runtime, err = require"acme/runtime".create {
   config = {
      acceptTerms = true, -- After accepting the provider's terms.
      email = "operator@example.com",
      domains = {"device.example.com"},
      production = false
   },
   -- These messages contain lifecycle codes and optional non-secret details.
   notify = function(code, msg) trace("ACME event ", code, msg or "") end
}
assert(runtime, err and (err.message or err.code))
runtime:start(function(result, problem)
   if not result then
      trace("ACME startup failed: ", problem.message or problem.code)
   end
end)

Automatic DNS-01 with SharkTrust

A SharkTrust portal publishes and removes the TXT record. When credentials are omitted, the shared DNS module uses the host's compiled etokengen or tokengen identity.

local runtime, err = require"acme/runtime".create {
   config = {
      acceptTerms = true, -- After accepting the provider's terms.
      email = "operator@example.com",
      domains = {"controller"},
      production = false,
      namePolicy = "exact",
      challenge = {type="dns-01", dns="local"}
   },
   notify = function(code, msg) trace("ACME event ", code, msg or "") end
}
assert(runtime, err and (err.message or err.code))
runtime:start(function(result, problem)
   -- The runtime retries startup failures while it remains open.
   if not result then
      trace("ACME startup failed: ", problem.message or problem.code)
   end
end)

For an explicit identity, set challenge.portalUrl, challenge.zoneKey, and challenge.proof(message) together. The client does not accept a secret option. A host callback calculates the proof from provisioned credentials. Keep credentials outside the application ZIP and source repository. The configuration fields are described below.

The runtime uses the first domain as the requested device name, then manages the name assigned by the portal. It stores registration with the ACME state unless the host supplies a custom store. Local IPv4 discovery is automatic; forward later address changes with runtime:setIpAddress(newIpAddress, callback).

If the configured portal or zone identity differs from the saved registration, startup automatically enrolls with the configured identity and replaces the local registration. It does not remove the device from the previous portal. Switching back therefore requires a new registration; namePolicy="exact" can report name_unavailable if the old device still owns that name.

Manual DNS-01 Example

Manual mode pauses issuance until an operator publishes the TXT record. It uses the same constructor; no separate adapter setup is required.

local runtime, err
runtime, err = require"acme/runtime".create {
   config = {
      acceptTerms = true, -- After accepting the provider's terms.
      email = "operator@example.com",
      domains = {"device.example.com"},
      production = false,
      challenge = {type="dns-01", mode="manual"}
   },
   notify = function(code)
      if code == 32 then
         local record = runtime.challenge:status()
         print("Create TXT record:", record.recordName, record.recordData)
      end
   end
}
assert(runtime, err and (err.message or err.code))
runtime:start(function(result, problem)
   -- Manual issuance stays pending until the operator confirms the TXT record.
   if not result then
      trace("ACME startup failed: ", problem.message or problem.code)
   end
end)

After a public DNS lookup returns the exact TXT value, continue the pending operation:

local challenge = runtime.challenge
if challenge:status().phase == "publish" then
   challenge:continue(function(ok, problem)
      -- This confirms publication; the startup callback reports final completion.
      if not ok then trace("DNS confirmation failed: ", problem.message or problem.code) end
   end)
end

The operator removes the TXT record after validation. Use runtime.challenge:cancel() to cancel the pending publication step.

Private Certificates with SharkCA

Use SharkTrust Private CA (SharkCA) for certificates covering private device names such as controller.local, local IPv4 addresses, or both. Devices enroll with your portal and obtain certificates over outbound HTTPS. They do not need a public DNS record or an inbound HTTP challenge.

Before running this example:

• Set up a portal and enrollment zone using the SharkCA installation instructions.
• Provision the host with a compiled identity for that zone. The portal's Download C code action generates the identity for host integration. An identity for a public SharkTrust zone cannot be used with an unrelated SharkCA zone.
• Install the zone's device CA root on the computers and applications that connect to the device.
• Make sure the device trusts the portal's HTTPS certificate. A portal using Let's Encrypt or another already trusted issuer needs no additional private root. For a private HTTPS portal, configure its verified portal CA with acme/http.setCertStore() before creating the runtime.

local runtime, err = require"acme/runtime".create {
   config = {
      domains = {"controller"}, -- Request a device name in the portal's zone.
      sharkca = {} -- Use the compiled identity for this SharkCA zone.
   },
   notify = function(code, msg) trace("ACME event ", code, msg or "") end
}
assert(runtime, err and (err.message or err.code))
runtime:start(function(result, problem)
   -- Startup enrolls the device and installs its certificate.
   if not result then
      trace("SharkCA startup failed: ", problem.message or problem.code)
   end
end)

Use domains={} for an IP-only certificate. The zone must permit IP issuance and the device's local address. SharkCA needs no email address, terms acceptance, or production/staging selector. Its certificates use Elliptic Curve Cryptography (ECC).

To enter credentials without rebuilding the host, use Mako's acme.sharkca settings or the Xedge certificate-settings interface. For an explicit identity in Lua, see SharkCA configuration. Choose one owner for the host's HTTPS certificates; do not also start this runtime when Mako or Xedge already manages them.

SharkCA issues certificates but does not provide DNS services. Named devices normally use multicast DNS (mDNS) on the local network. Mako's configuration and Xedge's settings provide name advertisement; a runtime created directly from Lua needs the host's name-resolution integration. Portal administration and trust distribution are covered in the SharkCA user manual.

Application Lifecycle

Call runtime:close(callback) during application unload. It cancels owned work, removes an active challenge when possible, closes network clients, and prevents new operations. On a device that starts before its clock is valid, wait for the clock synchronization event before calling start(). Certificate validation and HTTPS server trust checks require a correct clock.

Mako users can configure the same runtime in mako.conf. Xedge users normally configure it in the Xedge certificate user interface.

In mako.conf, acme.challenge.secret is an optional 64-character hexadecimal string that can replace proof when supplied with portalUrl and zoneKey. Mako creates the proof callback before calling the shared runtime; an explicit proof callback takes precedence. Direct callers of Runtime.create() and Dns.createClient() must still supply a proof callback for an explicit identity.

Module Guide

The certificate manager is created through acme/runtime; the SharkTrust client is created through acme/dns. You do not need separate manager or SharkTrust modules. The package also contains acme/_util and acme/_server, which are private host implementation details.

Runtime and Build Requirements

The modules require the auxiliary Lua bindings, an HTTPS client with a trusted CA store, a valid system clock, and private writable storage. The I/O interface is the BAS object used to read and write that storage. A BAS build that creates software keys and certificate signing requests (CSRs) must enable these SharkSSL options:

#define SHARKSSL_ENABLE_ASN1_KEY_CREATION 1
#define SHARKSSL_ENABLE_RSAKEY_CREATE     1
#define SHARKSSL_ENABLE_ECCKEY_CREATE     1
#define SHARKSSL_ENABLE_CSR_CREATION      1

Add missing definitions to the platform's inc/arch/[platform]/TargConfig.h or compiler options. RSA certificate keys also require RSA support in the SharkSSL build. Mako Server and Xedge packages that include the ACME plugin provide the required integration.

A Trusted Platform Module (TPM) can hold private ECC keys and perform signing without exposing those keys to Lua. The stack uses the host's TPM interface when available; otherwise it creates software keys. See TPM interface for a custom host.

Common API Conventions

Callbacks and Errors

Asynchronous methods use callback(result, err). On success, result contains a value and err is nil. On failure, result is nil and err is a structured error table. A storage load() callback may return nil, nil to mean that no saved state exists.

• function callback(result, err) - completion function called once after an asynchronous operation starts.
  • any result - the successful result documented for the method. Most methods return a table or Boolean true.
  • table err - nil on success. On failure, this is the error table described below.

{
   code = "bad_nonce",
   message = "The ACME server rejected the replay nonce",
   temporary = true,
   status = 400,
   type = "urn:ietf:params:acme:error:badNonce",
   detail = "...",
   retryAfter = 15,
   operation = "newOrder",
   url = "https://acme.example/directory/new-order"
}

• string code - stable short error identifier for program logic.
• string message - human-readable description suitable for diagnostics.
• boolean temporary - true when retrying later may succeed.
• boolean retryable - false excludes the short transient-error backoff even when temporary is true. Runtime startup still retries once per hour while open.
• number status - optional HTTP status code.
• string type and string detail - optional ACME problem type and provider detail.
• number retryAfter - optional provider-requested delay in seconds.
• string operation and string url - optional failed protocol operation and endpoint.
• string cause and string phase - optional transport cause and phase. phase is request, write, or read.
• table cleanup or table rollback - optional secondary error raised while cleaning up or restoring earlier state.

A method may return nil, err before it starts, usually because an argument is invalid or the object is closed. After an asynchronous operation starts, its callback is invoked once. Transport errors can include cause and phase, where the phase is request, write, or read.

Lua callers must supply the documented argument types, supported option values, and callbacks. Internal calls do not repeat every argument or interface check. Incorrect Lua API use is a programming error; do not depend on an invalid_* result for every malformed argument. Network responses, persisted credentials, service identity, terms acceptance, and operation lifecycle still receive the required checks.

Lifecycle Notifications

The optional notify(code, msg) callback reports lifecycle events. code is an integer. msg is a string for codes 3 and 13, and nil for the other codes. Use these events to update a user interface or write an application log. The callback returns no value, must return promptly, and must not yield. Callback errors are caught and traced.

Ignore unknown future codes. Only codes 3 and 13 carry the message described above. Certificate events do not identify a domain; refresh runtime:status() to find the current state. Use completion callbacks for operation results and detailed errors. For code 32, read challenge:status() for the TXT record, then call continue() or cancel() through the host interface.

ACME Service Options

local service = {
   production = false,
   productionUrl = "https://acme.example/production/directory",
   stagingUrl = "https://acme.example/staging/directory",
   http = {
      proxy = "proxy.example.com",
      proxyport = 8080,
      shark = trustedSharkSslClient
   }
}

The service table selects the ACME directory:

• table service - ACME service configuration.
  • boolean production - required. Set to true for the production directory or false for the staging directory.
  • string productionUrl - optional HTTPS directory URL used instead of the built-in Let's Encrypt production URL.
  • string stagingUrl - optional HTTPS directory URL used instead of the built-in Let's Encrypt staging URL.
  • table http - optional BAS HTTP client options, such as a proxy or custom trusted SharkSSL client object. Server certificate validation is always enabled.

The selected directory URL identifies an ACME account and certificate profile. Staging and production state are kept separate. Changing the active directory through the manager or runtime uses a transactional service switch, described under manager:switchService().

Module acme/runtime

acme/runtime is the recommended high-level API. It creates an engine and manager, selects the HTTP or DNS challenge adapter, restores saved state, starts renewal, and closes the owned objects in the correct order.

Runtime.create(options)

Creates the high-level certificate runtime. Use this constructor for normal application integrations. Mako and Xedge configuration users do not call it because those hosts create the runtime automatically.

local Runtime = require"acme/runtime"
local runtime, err = Runtime.create(options)

Parameters

• table options - Runtime settings listed below, including config (table).

• table or userdata io - Required for standalone BAS. Private, writable BAS I/O interface. The runtime stores ACME accounts, certificate records, software private keys, and its default SharkTrust registration below this I/O. Mako, including Xedge hosted on Mako, defaults to home; standalone Xedge defaults to disk. Xedge's built-in integration passes its selected I/O explicitly.
• function install - Required for standalone BAS or custom listeners. install(records, callback) activates the complete certificate set. Mako Server and Xedge provide a default for their standard HTTPS listeners. Supply this function when embedding BAS directly or when any host uses custom listeners.
• table config - Required. Common configuration, with the same fields as the top-level Mako acme table.
• table store - Optional. Custom persistent registration store with load(callback) and save(state, callback) functions. Automatic DNS uses sharktrust.json below the runtime's storage directory when this option is omitted. See SharkTrust state storage.
• table http - Optional. HTTP client options, such as proxy settings, passed to both the ACME service and SharkTrust. Mako supplies its configured proxy automatically.
• table challenge - Optional. Custom challenge adapter with type, present, and cleanup. Used when config.challenge does not select a built-in DNS mode.
• string path - Optional. Storage directory below io. The default is acme.
• table tpm - Optional. TPM interface for a standalone integration. ECC keys use it automatically. Mako and Xedge install their TPM integration without this option.
• function notify - Optional. notify(code, msg) receives an integer lifecycle code and an optional string message.
• function renewAllowed - Optional. renewAllowed(domain, expiresAt) is called before a scheduled renewal. domain is a string and expiresAt is the certificate expiration as a numeric Unix timestamp in seconds, or nil if unavailable. No certificate or private key is passed. Return false to defer the renewal for one hour. Any other return value permits it. Forced renewal ignores this callback. The callback must not throw; its Lua errors propagate and interrupt scheduled renewal processing.

Return values

• table runtime - on success, or nil, err (table) when construction is rejected. Codes include invalid_options, invalid_io, invalid_installer and terms_not_accepted; DNS setup errors are forwarded. The constructor creates the components but does not start certificate management.

Throws

The listed validation failures return errors. Incorrect field types or missing required nested fields can raise Lua errors. Errors from supplied components and native setup can propagate. Most configuration and key validation occurs later during startup.

Common Configuration

Pass this table as options.config on every host, or as acme in mako.conf. Direct Lua callers supply the documented types. Host UI input validation stays at the UI boundary.

• boolean acceptTerms - Required and true for public-CA flows; omitted and unused with SharkCA.
• string email - Required account contact email for public-CA flows; omitted and unused with SharkCA.
• table domains - Required array of domain strings. Public-CA flows require a non-empty array; automatic DNS uses its first entry for enrollment. SharkCA accepts zero or one device name; zero selects IP-only issuance.
• boolean production - Optional; defaults to true. Set false for staging.
• string productionUrl, string stagingUrl - Optional HTTPS directory overrides; default to the Let's Encrypt production and staging directories.
• string keyType - Optional; ecc (default) or rsa.
• number bits - Optional RSA key size in bits; default 2048.
• string curve - Optional ECC curve name; default SECP384R1.
• string namePolicy - Optional SharkTrust or SharkCA enrollment policy: increment (default) or exact.
• string info - Optional SharkTrust or SharkCA device description, at most 256 bytes.
• boolean cleanup - Optional; defaults to true. Removes saved certificate records for domains no longer configured.
• number timeout, number dnsResolveTimeout - Optional operation and DNS resolution timeouts in seconds; see the engine certificate options.
• number fallbackRenewBefore - Optional fallback renewal lead time in seconds; default 22 days, minimum 3600. The effective lead time is capped at one third of the certificate validity period, with proportionally limited random variation, so short-lived certificates do not immediately renew.
• table challenge - Optional built-in DNS settings described below. Omit for HTTP-01 or SharkCA.
• table sharkca - Optional; selects SharkCA private enrollment. Mutually exclusive with challenge. Public production/staging fields are unused in this profile.

The optional challenge table selects type="dns-01" (string). Its optional mode is automatic (default) or manual (string). Automatic mode accepts portalUrl (HTTPS string), zoneKey (64-character hex string), and proof(message) (required function returning 32 binary bytes for a string message). See the proof callback contract. Omit the identity fields to use the compiled identity. Optional dns is local (default), wan, or both (string); reverse is a boolean defaulting to false; propagationDelay is seconds (number, default 30, zero allowed). Manual mode needs only type and mode.

SharkCA Configuration

Set config.sharkca to a table to select the private enrollment profile. An empty table uses the host's compiled zone identity. For an explicit identity, supply the following fields together:

• string portalUrl - Required for an explicit identity. HTTPS portal root URL, optionally including its port, or the exact /sharktrust.lsp endpoint. With a compiled identity, this field is optional and defaults to that identity's portal address; a supplied URL overrides the address.
• string zoneKey - Required for an explicit identity. Exactly 64 hexadecimal characters identifying the portal zone. Omit it together with proof to use the compiled identity.
• function proof(message) - Required for an explicit identity. Receives a binary-safe string and returns a 32-byte binary HMAC-SHA-256 result. It must not yield. See the host proof callback for the full contract.

config.domains is a required array containing zero or one device-name string. Use {"controller"} for a name or {} for IP-only issuance. The portal's zone policy selects the approved certificate names and addresses. The profile supports ECC keys only and does not accept config.challenge. Email, terms acceptance, and public production/staging fields are unused. There is no fallback to a public ACME service.

The secret and caFile fields belong to Mako's configuration loader, which derives the proof callback and loads a PEM trust file. Direct Runtime.create() callers supply the proof callback themselves and configure portal HTTPS trust when the existing trust store does not trust the portal's issuer.

Certificate Installation Callback

The manager calls this function whenever its active certificate set changes. Replace a non-empty set atomically if possible. An empty records array means the manager has no certificates to supply; the host determines how to handle its existing HTTPS listeners. Mako and Xedge applications normally omit this callback because their standard HTTPS listeners use the built-in installer.

The built-in installer intentionally leaves the currently installed certificates in place when records is empty. It does not switch to the self-signed default. Thus removing or revoking the last managed certificate does not immediately stop the listeners from presenting it. The installed set remains until another non-empty set replaces it or the host restarts. A custom installer must define its own empty-set behavior.

local function installCertificates(records, callback)
   -- Convert each record for the platform and replace the active TLS set.
   -- Call callback only after every record is active, or after the update fails.
   callback(true, nil)
end

Parameters

• table records - sorted array of the complete active certificate set. Each record contains domain (string), certificate (string, PEM chain) and privateKey (string, software PEM key, or table, TPM descriptor).
• function callback - call exactly once with result (boolean or nil) and err (string, table or nil). Use true, nil after the entire set is active, or nil, err on failure. A table error supplies message (string).

Return values

The installer's direct return values are ignored. Completion must use callback, synchronously or asynchronously. The manager remains busy until completion; it does not interpret a direct nil, err return as failure.

Throws

Installer exceptions and callback-reported failures become certificate_install_failed error tables. For a table error, the manager keeps its message; other error fields are not forwarded. Duplicate completion calls are ignored. An exception after completion does not replace the completed result.

SharkTrust Registration

The client discovers the local IPv4 address used for the portal connection and sends it during enrollment. The application supplies only the naming, DNS publication, and descriptive fields below.

The registration table supplies SharkTrust enrollment data:

{
   name = "controller",
   namePolicy = "exact",
   dns = "local",
   info = "BAS controller"
}

• string name - Optional. Preferred DNS label or full name in the SharkTrust zone. The portal assigns a name when omitted.
• string namePolicy - Optional. exact rejects an unavailable requested name. increment permits a numbered alternative. An explicit name defaults to exact.
• string dns - Optional. Address publication mode: local, wan, or both. The default is local. See Selecting the Published Address.
• string info - Optional. Device description of at most 256 bytes.
• string credential - Optional for direct client enrollment. Exactly 64 lowercase hexadecimal characters representing 32 cryptographically random bytes. Persist before sending and reuse for retries. The returned credential must match or completion reports enrollment_credential_mismatch. The normal DNS adapter generates this value itself. Without a supplied credential, a lost write/read response remains enrollment_state_unknown with retryable=false.

Runtime Methods

runtime:start(callback)

Starts certificate management. Call this once after storage, networking, DNS, and the system clock are ready. It restores saved certificates and SharkTrust registration, enrolls when needed, obtains missing certificates, and starts renewal.

For SharkCA, startup saves the account key before enrollment, checks the portal's sharkca-v1 capability and account association, and restores saved registration before requesting a certificate. The runtime manages one stable $device certificate record.

Parameters

• function callback - optional completion callback receiving result (table or nil) and err (table or nil). On success, result is a table whose boolean started member is true when this call started the runtime or false when it was already running. A new or changed service profile adds table switch with boolean changed, boolean reused, and number rebuilt. A non-fatal registration check can add table warning containing the structured error. On failure, result is nil and err is the error table.

The method is idempotent. Every reported startup failure is returned to the callback and retried in the background while the runtime remains open. Temporary, retryable errors use a delay starting at 30 seconds and doubling to five minutes. Other errors, including name_unavailable, retry once per hour. There is no attempt limit. Closing the runtime cancels retry. Incorrect configuration, unavailable storage or an occupied name may still need operator correction.

Return values

• boolean accepted - true when startup is submitted or the runtime is already started. A closed runtime or overlapping startup reports its error to the callback and returns no values. Completion may run before this method returns.

Throws

Reported storage, enrollment, issuance and installation failures use the callback. Completion callback errors are caught and traced. Incorrect arguments or supplied components may raise Lua errors.

runtime:isRegistered(callback)

Checks the current device registration with SharkTrust and refreshes the portal with the automatically discovered local IPv4 address. Use it for diagnostics or a registration-status user interface. Normal startup performs this work automatically.

Parameters

• function callback - required completion callback receiving result (table or nil) and err (table or nil). Failure is nil, err. On success, result contains boolean registered and may contain string deviceId and string name when registered. With the built-in DNS client, string sockname is the local IPv4 address of the connection to the portal. Without a SharkTrust configuration, err.code is sharktrust_not_configured.

Return values

• boolean accepted - true after dispatch to the DNS adapter; the callback reports the outcome. Without SharkTrust configuration, the callback receives nil, err (table) with code sharktrust_not_configured and the method returns no values.

For SharkCA, this method resumes the saved registration and applies the portal's approved certificate identifiers. When they change, success is reported only after the replacement certificate is installed. Failure leaves the previous certificate installed. Address-change behavior and overlapping operations are described under setIpAddress().

Throws

Reported storage and portal failures use the callback. Callback errors are caught and traced. Errors raised by supplied components can propagate.

runtime:isAvailable(name, callback)

Checks whether a requested SharkTrust device name appears available. Use it only as an advisory user-interface check. Enrollment performs the authoritative check and can still report a conflict.

Parameters

• string name - requested DNS label or full name, from 1 through 253 characters.
• function callback - required completion callback receiving result (table or nil) and err (table or nil). Failure is nil, err. On success, result is {available=boolean, name=string}, where name is the normalized full name.

Return values

• boolean or nil accepted - true when the portal check is scheduled. A closed portal client returns nil, err (table) and also invokes the callback. Without SharkTrust configuration, the callback receives nil, err (table) with code sharktrust_not_configured and the method returns no values.

Throws

Reported portal failures use the callback. Callback errors are caught and traced. Incorrect arguments or supplied components may raise Lua errors.

runtime:setIpAddress(ipAddress, callback)

Updates the local IPv4 address stored by the portal. SharkTrust refreshes the DNS A record; SharkCA replaces the certificate when the approved identifiers change. Use it after startup when DHCP or another network event reports that the device address changed. Startup discovery and the first update are automatic.

Parameters

• string ipAddress - new IPv4 address in dotted-decimal form, such as 192.168.1.20.
• function callback - required completion callback receiving result (table or nil) and err (table or nil). Failure is nil, err. On success, result is the portal acknowledgement table. Without a SharkTrust configuration, err.code is sharktrust_not_configured.

Return values

• boolean accepted - true after dispatch to the DNS adapter; the callback reports the outcome. Without SharkTrust configuration, the callback receives nil, err (table) with code sharktrust_not_configured and the method returns no values.

For SharkCA, call this method after startup. The runtime saves accepted registration changes, keeps the $device record's private key, and installs a replacement certificate when the approved identifiers change. Its callback receives the portal registration result only after installation succeeds. If replacement fails, the previous certificate stays installed.

An overlapping portal update can report operation_in_progress; retry it after the current callback. If the identifiers change during issuance, the superseded request can report identifiers_changed while the runtime proceeds with the latest identifiers. Calling before SharkCA startup reports runtime_not_started.

Throws

Reported storage and portal failures use the callback. Callback errors are caught and traced. Incorrect arguments or supplied components may raise Lua errors.

runtime:reverseConnection(enable)

Changes the SharkTrust reverse-connection state immediately. Use it when an application lets an operator enable or disable portal-assisted remote access after startup.

Parameters

• boolean enable - true enables the connection and false disables it.

Return values

• boolean or nil result - true on success. Failure is nil, err (table), including sharktrust_not_configured, client_closed, not_enrolled, proof_failed or reverse_connection_unavailable. SharkCA does not support reverse connections and returns sharkca_reverse_unavailable. This synchronous method has no completion callback.

Throws

Reported configuration and proof failures return nil, err. Native reverse-connection option errors and exceptions from supplied components can propagate.

runtime:switchService(service, callback)

Moves certificate management to another ACME directory. Use it to change between staging and production or to select another compatible provider. Existing certificates stay installed until the new profile is ready. SharkTrust registration does not change.

Parameters

• table service - ACME service options with required boolean production.
• function callback - required completion callback receiving result (table or nil) and err (table or nil). Failure is nil, err. On success, result contains boolean changed, boolean reused, and, when rebuilding, number rebuilt.

Return values

• boolean or nil accepted - true for accepted work; some early rejections return nil, err (table), while others report only through the callback. Forwards the direct returns and callback results of manager:switchService() with rebuild=true. Check the callback for completion.

SharkCA does not switch directories through this method; its callback reports sharkca_reconfigure_required. Close the runtime and create it again with the new portal configuration.

Throws

Uses the exception and error-reporting behavior documented for manager:switchService().

runtime:renew(domain, callback)

Immediately requests a replacement certificate even when the current certificate is not near expiration. Use it for an operator-requested renewal or after a certificate-related policy change. Scheduled renewal needs no application call.

Parameters

• string or nil domain - one domain already managed by a public-CA runtime. For SharkCA, pass nil; the runtime renews its single $device record.
• function callback - required completion callback receiving result (table or nil) and err (table or nil). Failure is nil, err. On success, result is the new certificate record. The current certificate remains installed until replacement succeeds.

Return values

• boolean or nil accepted - true after starting. A missing domain returns nil, err (table) and also invokes the callback. Busy or closed manager errors use only the callback. Forwards the direct returns and callback results of manager:renew() with force=true.

Throws

Uses the exception and error-reporting behavior documented for manager:renew().

runtime:status()

Returns an operational snapshot for status pages, diagnostics, and health checks. The built-in components do not include private keys or device credentials.

Parameters

None. Additional arguments are ignored.

Return values

• table status - A new manager status snapshot, extended with startup, challenge-adapter, and reverse-connection status as shown below. This method does not return an operational nil/error pair.

{
   loaded = true,
   started = true,
   closed = false,
   starting = false,
   retryPending = false,
   operation = nil,
   directoryUrl = "https://acme.example/directory",
   domains = {},
   jobs = {},
   lastError = nil,
   retryAt = nil,
   registration = challengeStatusOrNil,
   reverse = {enabled=true, connected=true, status=202, connections=3}
}

• boolean loaded - true after saved manager state has been read.
• boolean started - true while certificate renewal management is running.
• boolean closed - true after close() prevents further work.
• boolean starting - true during an active startup attempt.
• boolean retryPending - true when a startup failure has scheduled another attempt.
• string|nil operation - active manager operation, or nil when idle.
• string|nil directoryUrl - active ACME directory, or nil before a profile is active.
• table domains - table keyed by domain. Each value contains numeric expiresAt, renewAt, and optional ARI fields.
• table jobs - array of active and queued engine job status tables.
• table|nil lastError - most recent manager error, or nil.
• number|nil retryAt - Unix timestamp for the next renewal retry, or nil.
• table|nil registration - selected challenge adapter's status, including manual DNS status. Nil when the adapter has no status() method or no adapter is selected. A custom adapter supplies its own status fields.
• table reverse - {enabled=boolean, connected=boolean, status=number, connections=number}.

Throws

Exceptions raised by an underlying status method, including a custom challenge adapter's status() method, propagate. Lua allocation errors can also propagate.

runtime:close(callback)

Stops certificate management and releases owned resources. Call it during application unload. It closes the manager and challenge adapter and cancels owned work.

Parameters

• function callback - Optional. Receives result (boolean or nil) and err (table or nil). On completion, result is true on success, or nil with err on failure. The manager's error takes precedence if both components fail. Completion can occur before or after this method returns.

Repeated close calls succeed immediately, without waiting for an earlier close to finish or retrying cleanup. Their callbacks receive true, nil.

Return values

• boolean or nil result - true when shutdown is requested. This return value does not report the cleanup outcome; use the callback.

If a custom certificate installer or automatic DNS registration operation is still pending, returns nil, err (string) with err equal to "busy". Registration operations include loading or saving state, enrollment and identity switching. Shutdown has not begun: both components remain open, timers are unchanged, and the supplied close callback is not called. Retry close after the operation finishes. The built-in installer completes synchronously.

Throws

Reported cleanup failures go to the callback as nil, err. Errors raised by the completion callback are caught and traced. A custom challenge adapter must follow its callback contract; an exception from its close() method is not converted to a cleanup error result.

runtime.challenge contains the selected challenge adapter. Most applications do not use it directly. A manual DNS user interface uses it to call status(), continue(), or cancel().

Module acme/dns

acme/dns creates DNS-01 challenge adapters. Use createSharkTrust() for automatic DNS updates or createManual() for an operator-assisted flow.

Dns.createSharkTrust(options)

Creates a DNS-01 challenge adapter that uses SharkTrust to publish TXT records and persists the device registration. Runtime.create() calls this constructor automatically when config.challenge selects automatic DNS-01. Call it directly only when assembling an engine and manager without the runtime.

local Dns = require"acme/dns"
local challenge, err = Dns.createSharkTrust {
   client = sharkTrustClient,
   store = {
      load = function(callback) callback(savedState, nil) end,
      save = function(state, callback) callback(true, nil) end
   },
   propagationDelay = 30,
   notify = function(code) end
}

Parameters

• table options - DNS adapter settings below.

• table client - required SharkTrust client.
• table store - required persistent store with function load(callback) and function save(state, callback), described below.
• number propagationDelay - optional delay in seconds between publishing the TXT record and asking the ACME service to validate it. The default is 30 and zero is permitted.
• function notify(code) - optional lifecycle notification callback. The callback receives one integer code.

Return values

• table challenge - on success, or nil, err (table) with code invalid_propagation_delay when the propagation delay is negative. No registration state is loaded and no TXT record is published during construction.

Throws

Incorrect options or a missing/incompatible client can throw. Store callbacks are used later; exceptions from store.load and store.save are converted to storage_read_failed and storage_write_failed errors.

SharkTrust State Storage

When used with acme/runtime, this store also retains ACME account keys or TPM key descriptors in an accounts table indexed by service ID. Save and restore the entire state table. Before enrollment, it may contain account state without a device credential. Xedge uses encrypted xcfg.bin; the default runtime store uses acme/sharktrust.json. Protect this store as private key material when software keys are used.

Both SharkTrustX and SharkCA can restore a deleted service profile from this retained account identity and obtain another certificate without changing the registered device or name. After upgrading an existing installation, let it start successfully with its original service file present before deleting that file. An account identity already lost before the upgrade cannot be restored by this feature. For normal forced renewal, use runtime:renew() instead of deleting files.

The adapter calls store.load and store.save as plain functions, without an implicit self argument. Both functions must call their callback exactly once:

store.load(callback)

Parameters

• function callback - receives state (table or nil) and err (string, table or nil). Pass the complete registration state on success; nil, nil means no saved state; nil, err reports a read failure. A table error supplies message (string).

Return values

Ignored. Report completion exactly once through callback.

Throws

Exceptions are caught and reported as storage_read_failed. Callback-reported errors use the same code, with the supplied message. Errors raised after completion do not replace the result.

store.save(state, callback)

Parameters

• table state - complete registration state described below.
• function callback - receives result (boolean or nil) and err (string, table or nil). Pass true, nil only after durable commit, or nil, err after failure. A table error supplies message (string).

Return values

Ignored. Report completion exactly once through callback. The adapter serializes saves and retains failed state for a later resume() retry.

Throws

Exceptions and callback-reported errors become storage_write_failed errors with the supplied message. Other table error fields are not forwarded. Duplicate completions and exceptions after completion do not replace the result.

callback(state, nil) -- load: state was found
callback(nil, nil)   -- load: no state exists
callback(nil, err)   -- load: read failed

callback(true, nil)  -- save: durable commit completed
callback(nil, err)   -- save: commit failed

• number version - Storage format version. The current value is 2.
• boolean or nil pending - true while enrollment is unfinished; absent after completed registration is saved.
• table or nil request - Original enrollment settings saved with a pending credential; absent after completed registration. Pending records do not yet have a portal-assigned deviceId or name. Preserve the entire state passed to the store.
• string portalUrl - Normalized SharkTrust endpoint that owns this registration.
• string zoneIdentity - Opaque, non-secret fingerprint used to reject state from another zone identity.
• string or nil deviceId - Public device identifier assigned by the portal; absent in pending enrollment state.
• string or nil name - Assigned fully qualified device name; absent in pending enrollment state.
• string credential - Secret 64-character hexadecimal device credential.
• number updatedAt - Unix timestamp in seconds recorded when the state changed.

save() must not report success until the data is durably committed. A filesystem implementation can write a temporary file and rename it. The adapter serializes save operations.

{
   version = 2,
   portalUrl = "https://portal.example.com/sharktrust.lsp",
   zoneIdentity = "<opaque-non-secret-fingerprint>",
   deviceId = "0123456789abcdef0123",
   name = "controller.example-zone.com",
   credential = "<64-lowercase-hexadecimal-characters>",
   updatedAt = 1788105600
}

The credential is secret. Protect it with the strongest storage available on the target. Do not place this state in an application ZIP, source repository, public resource, log, or diagnostic download. The adapter rejects malformed state and state belonging to another portal or zone identity.

Automatic DNS Adapter Methods

Direct returns acknowledge submission; callbacks report completion and may run before the method returns. Use the runtime methods for ordinary application code.

challenge:enroll(request, callback)

Registers the device and saves its assigned identity.

Parameters

• table request - enrollment settings.
• function callback - receives state (table or nil) and err (table or nil). Success supplies the persisted registration state; failure supplies nil, err.

Return values

• boolean accepted - true after starting. Busy or closed rejection reports an error through the callback and returns no values.

Throws

Callback errors are caught and traced. Reported storage or portal failures use the callback. Errors from incorrect arguments or supplied client/timer implementations can propagate.

challenge:isAvailable(name, callback)

Performs an advisory name-availability check; enrollment makes the final decision.

Parameters

• string name - requested DNS label or full name, 1 through 253 characters.
• function callback - receives result (table or nil) and err (table or nil). Success supplies result.available (boolean) and result.name (string), the normalized full name.

Return values

• boolean or nil accepted - true when scheduled. A closed client returns nil, err (table) and invokes the callback.

Throws

Callback errors are caught and traced. Reported storage or portal failures use the callback. Errors from incorrect arguments or supplied client/timer implementations can propagate.

challenge:load(callback)

Loads and validates saved registration state. Concurrent loads share the same pending read.

Parameters

• function callback - receives state (table or nil) and err (table or nil). Success supplies a copy of the registration state; missing state is nil, nil; failure is nil, err.

Return values

• boolean accepted - true. The callback can run synchronously, including when state is already loaded or the adapter is closed.

Throws

Callback errors are caught and traced. Reported storage or portal failures use the callback. Errors from incorrect arguments or supplied client/timer implementations can propagate.

challenge:resume(callback)

Confirms saved registration with the portal and persists a changed assigned name. First retries a pending failed state save.

Parameters

• function callback - receives result (table or nil) and err (table or nil). Success supplies result.registered (boolean), with result.deviceId and result.name (string, optional). Failure is nil, err.

Return values

• boolean accepted - true on the normal path. Retrying a pending save returns no values; its completion still uses the callback.

Throws

Callback errors are caught and traced. Reported storage or portal failures use the callback. Errors from incorrect arguments or supplied client/timer implementations can propagate.

challenge:isRegistered(callback)

Checks registration and updates the portal with the automatically discovered local IPv4 address.

Parameters

• function callback - receives result (table or nil) and err (table or nil). Success supplies result.registered (boolean), with result.deviceId and result.name (string, optional). The built-in client also supplies result.sockname (string), the local IPv4 address of the connection to the portal. Failure is nil, err.

Return values

• boolean accepted - true after dispatch. Missing state, a closed adapter and operational failures are reported through the callback.

Throws

Callback errors are caught and traced. Reported storage or portal failures use the callback. Errors from incorrect arguments or supplied client/timer implementations can propagate.

challenge:setIpAddress(ipAddress, callback)

Updates the registered local IPv4 address after a network-address change.

Parameters

• string ipAddress - dotted-decimal IPv4 address.
• function callback - receives result (table or nil), the portal acknowledgement, and err (table or nil). Failure is nil, err.

Return values

• boolean accepted - true after dispatch. Missing state, a closed adapter and operational failures are reported through the callback.

Throws

Callback errors are caught and traced. Reported storage or portal failures use the callback. Errors from incorrect arguments or supplied client/timer implementations can propagate.

challenge:getWan(callback)

Reads the public IPv4 address observed by the portal.

Parameters

• function callback - receives result (table or nil) and err (table or nil). Success supplies result.ipAddress (string). Failure is nil, err.

Return values

• boolean accepted - true after dispatch. Missing state, a closed adapter and operational failures are reported through the callback.

Throws

Callback errors are caught and traced. Reported storage or portal failures use the callback. Errors from incorrect arguments or supplied client/timer implementations can propagate.

challenge:switchIdentity(value, options, callback)

Replaces the portal client. Changing the portal or zone identity requires enrollment and persistence before replacing the active registration.

Parameters

• table value - contains client (table), the replacement SharkTrust client.
• table or nil options - for an identity change, reenroll (boolean) must be true and enrollment (table) supplies enrollment settings.
• function callback - receives result (table or nil) and err (table or nil). Success supplies result.changed (boolean), plus result.state (table) after re-enrollment. Failure is nil, err.

Return values

• boolean or nil accepted - true when accepted. Missing re-enrollment permission or settings returns nil, err (table) and invokes the callback. Busy or closed rejection on the identity-change path uses only the callback. Replacing a client with the same identity returns true and result.changed=false without re-enrollment.

Throws

Callback errors are caught and traced. Reported storage or portal failures use the callback. Errors from incorrect arguments or supplied client/timer implementations can propagate.

challenge:present(context, callback)

Publishes the TXT record and waits for the propagation delay. Called by the ACME engine.

Parameters

• table context - engine-provided DNS challenge context.
• function callback - receives result (boolean or nil) and err (table or nil). Success is true, nil after publication and the configured delay. Cancellation or failure is nil, err.

Return values

• boolean or nil accepted - true after dispatch. If a challenge already exists, returns nil, err (table), with code challenge_in_progress, and also invokes the callback.

Throws

Callback errors are caught and traced. Reported storage or portal failures use the callback. Errors from incorrect arguments or supplied client/timer implementations can propagate.

challenge:status()

Reads a non-secret status snapshot.

Parameters

None.

Return values

• table status - contains type (string, "sharktrust"), loaded, enrolled, pendingSave and busy (boolean), and portalUrl (string). busy is true while registration loading, saving, enrollment or identity switching is pending. pendingSave identifies state retained after a failed save; it does not by itself mean a save is still running. name and deviceId (string or nil) identify the loaded registration. operation (string or nil) is "enroll" or "switchIdentity" while either operation is active. challenge (table or nil) contains recordName (string) and ready (boolean) while a challenge is active.

Throws

Does not throw for valid adapter state.

See the separate cleanup() and close() contracts below.

challenge:cleanup(context, callback)

Clears the active challenge and cancels its propagation timer. A pending present() callback receives nil and an error table with code challenge_cancelled. When registration state exists, cleanup requests removal of the TXT record.

Parameters

• table context - the engine-provided challenge context.
• function callback - receives result (table, boolean or nil) and err (table or nil). Success returns the portal acknowledgement table, or true if no result is supplied and no error occurs. Failure supplies nil, err. Without registration state, the callback receives true, nil immediately and no removal request is made.

Return values

• boolean result - true when removal is requested. Without registration state, returns no values. The callback reports the outcome.

Throws

Removal failures are reported through the callback. Errors from the pending present() callback or completion callback are caught and traced. Incorrect use of a supplied client or timer may throw.

challenge:close([callback])

Cancels the pending challenge and its propagation timer. If a registration and active challenge exist, it attempts to remove the TXT record before closing the client. Client cleanup proceeds even when record removal fails.

Parameters

• function callback - Optional. Receives result (boolean or nil) and err (table or nil). Success is true, nil. Failure is nil, err. If both record removal and client close fail, err is the record-removal error. Completion may occur before or after this method returns.

Return values

• boolean or nil result - true when shutdown starts. While registration loading, saving, enrollment or identity switching is pending, returns nil, err (string), with err equal to "busy". Nothing is closed or cancelled and the supplied close callback is not invoked. Retry after the operation finishes. A completed failed save does not prevent close merely because pendingSave remains true.

After shutdown has started, repeated calls return no values and invoke the supplied callback immediately with true, nil. They neither wait for the first call nor retry failed cleanup.

Throws

Reported removal and close failures are delivered to the callback. Completion callback errors are caught and traced. A supplied client must implement the documented methods and callback contracts; errors from incorrect client usage are not converted to cleanup error results.

switchIdentity() is required when the portal URL, zone key, zone secret, or generated proof identity changes. Without explicit re-enrollment permission, it returns sharktrust_identity_change_requires_reenrollment. An ACME production or staging change does not change SharkTrust identity.

challenge:switchIdentity(
   {client = newClient},
   {
      reenroll = true,
      enrollment = {
         name = "controller",
         namePolicy = "exact",
         dns = "local",
         info = "BAS controller"
      }
   },
   function(result, err)
      -- result.changed is true when the identity was replaced.
      -- result.state contains the newly saved registration state.
   end)

Dns.createManual(options)

Creates an operator-assisted DNS-01 adapter. Use it when the application cannot update DNS automatically and can show the TXT record to an operator.

local challenge = Dns.createManual {
   -- Code 32 tells the host to read challenge:status() and display the TXT record.
   notify = function(code) end
}

Parameters

• table options - optional adapter settings:
  • function notify(code) - optional notification callback. Its code argument (integer) is 32 when TXT publication is required. Read the record name and value from status().

Return values

• table challenge - Manual DNS challenge adapter, initially idle. Creating it does not publish a DNS record or start issuance.

Throws

Throws if options cannot be used as an options table. Notification callback errors are caught and traced when a notification is delivered.

The manual adapter implements present(context, callback) and cleanup(context, callback) for the engine. Application code uses these methods:

challenge:status()

Returns the information needed to display the pending DNS record.

Parameters

None.

Return values

• table status - A new table containing the fields below.
• string status.type - Always manual.
• string status.phase - idle, publish or active. After close(), the phase is idle; this field does not indicate whether the adapter is closed.
• string or nil status.recordName - TXT record name, absent when no challenge context is retained.
• string or nil status.recordData - TXT record value, absent when no challenge context is retained.

Throws

Does not deliberately throw for a valid adapter and challenge context.

challenge:continue([callback])

Continues validation after the operator confirms that the TXT record is publicly visible.

Parameters

• function callback - Optional. Receives result (boolean or nil) and err (table or nil). On success it receives true, nil after the waiting engine callback runs. Without a pending action, it receives nil and an error table with code no_pending_action. The callback runs before this method returns.

Return values

• boolean or nil result - true after releasing the pending action. Otherwise returns nil, err (table), with code no_pending_action. The same error table is passed to the callback when supplied.

Throws

No pending action is reported as an error result. Errors raised by the engine or completion callback are caught and traced.

challenge:cancel([callback])

Cancels the pending operator action and returns the adapter to idle. The engine's pending present() callback receives nil and an error table with code challenge_cancelled.

The old action is cleared before its callback runs, so a callback can cancel again or start a new action without notifying the old action twice.

Parameters

• function callback - Optional. Receives result (boolean) equal to true and err (nil), before this method returns.

Return values

• boolean result - true, including when no action is pending.

Throws

Errors raised by the engine or completion callback are caught and traced.

challenge:close([callback])

Closes the adapter and cancels any pending action. Later engine present() calls fail with adapter_closed. Repeated close calls succeed.

Parameters

• function callback - Optional. Receives result (boolean) equal to true and err (nil), before this method returns.

Return values

• boolean result - true.

Throws

Errors raised by cancellation or completion callbacks are caught and traced.

The module does not send email. A host may display the manual adapter status in a user interface or forward it through its own email service.

Certificate Manager

The manager in acme/runtime owns persistent ACME state, certificate installation, renewal scheduling, revocation, and service profiles. Most applications should use acme/runtime. Use the manager directly only when the application must assemble these responsibilities separately from SharkTrust or other runtime services.

Runtime.createManager(options)

The manager is a lower-level API and therefore always requires a certificate installer. In the example, installCertificates is the host function defined by the certificate installation callback contract. Mako and Xedge automatic installation applies to Runtime.create(), not to a manager constructed directly.

local Runtime = require"acme/runtime"
local manager, err = Runtime.createManager {
   io = writableIo,
   engine = engine,
   install = installCertificates, -- host callback described above
   notify = function(code) end,
   renewAllowed = function(domain, expiresAt) return true end,
   path = "acme"
}

Parameters

• table options - manager settings below.

• table|userdata io - required private, writable BAS I/O interface.
• table engine - required ACME engine.
• function install(records, callback) - required certificate installation callback. This callback is required when using the manager directly, including on Mako or Xedge.
• function notify(code) - optional lifecycle notification callback.
• function renewAllowed(domain, expiresAt) - optional scheduled-renewal policy. domain is a string and expiresAt is the certificate expiration as a numeric Unix timestamp in seconds, or nil if unavailable. No certificate or private key is passed. Return false to defer renewal for one hour. Any other result permits it. Forced renewal ignores this callback. The callback must not throw; its Lua errors propagate and interrupt scheduled renewal processing.
• string path - optional storage directory below io. The default is acme.

Return values

• table manager - on success, or nil, err (table) with code invalid_installer or invalid_io. Construction does not load storage, install certificates or start renewal. Call configure() before start().

Throws

A missing or incorrectly typed options argument can throw. Incorrect path types can throw during construction; I/O, engine and callback interfaces must satisfy their documented contracts and are used later.

manager:configure(config)

Sets the desired domains, ACME service, challenge adapter, and certificate-key policy. Call it before start() when using the manager directly. Calling it does not contact the ACME service.

local ok, err = manager:configure {
   email = "operator@example.com",
   domains = {"device.example.com"},
   acceptTerms = true,
   service = {production = false},
   challenge = challengeAdapter,
   key = {type = "ecc", curve = "SECP384R1"},
   cleanup = true,
   timeout = 600,
   dnsResolveTimeout = 30,
   fallbackRenewBefore = 22 * 24 * 60 * 60
}

• string email - Required. Non-empty ACME account contact email address.
• table domains - Required. Non-empty array of domain-name strings. Names are converted to lowercase and duplicates are removed. The manager requests one certificate per domain.
• boolean acceptTerms - Required. Must be true. The engine registers a new account only after this explicit acceptance.
• table service - Required. ACME service options with required boolean production.
• table challenge - Optional. Challenge adapter with string type, function present(context, callback), and function cleanup(context, callback). Omit it for the built-in HTTP-01 adapter.
• table key - Optional. Certificate-key settings: string type is ecc (default) or rsa; string curve defaults to SECP384R1 for ECC; number bits defaults to 2048 for RSA.
• boolean cleanup - Optional. When true, remove saved certificate records for domains no longer listed. Direct manager use defaults to false. Runtime.create() passes its configured value.
• number timeout - Optional. Maximum number of seconds spent polling an ACME challenge or order. The default is 600.
• number dnsResolveTimeout - Optional. DNS resolution timeout in seconds supplied to a DNS-01 adapter. The default is 30.
• number fallbackRenewBefore - Optional. Seconds before certificate expiration used when ACME Renewal Information is unavailable. The default is 22 days and the minimum configurable value is one hour. The effective lead time is capped at one third of the certificate validity period, with proportionally limited random variation.

Parameters

• table config - Configuration fields listed above. The manager copies configuration values except the challenge adapter, which it retains by reference. Domain strings are lowercased and duplicates removed.

Return values

• boolean or nil result - true when configuration is accepted. Otherwise returns nil, err (table), preserving the previous accepted configuration. Error codes include manager_closed, invalid_configuration, terms_not_accepted, invalid_service and invalid_directory_url. This synchronous method does not issue or install a certificate.

Throws

Configuration validation failures use the error results above. Supply the documented types and ordinary configuration tables; values that cannot be copied or used by the configured components may raise Lua errors. Errors from later operations are reported by those operations.

ECC certificate keys use the platform TPM when its key interface is available; otherwise they are created as software keys. RSA keys are always software keys.

Manager Methods

manager:load(callback)

Loads saved state and installs the active certificate set without contacting an ACME service. Repeated calls reinstall the loaded active profile without reading storage again. The runtime calls this during startup.

Parameters

• function callback - receives result (boolean or nil) and err (table or nil). Success is true, nil, including when no saved state exists. Storage or installation failure is nil, err. Completion runs once, after the installer completes when a profile is active.

Return values

• boolean result - true when a storage load is scheduled. If state is already loaded, returns no values. Use the callback for the outcome; it may run before or after this method returns.

Throws

Installer exceptions are converted to certificate_install_failed errors. Completion callback errors are caught and traced. Incorrect use of a supplied storage or scheduling interface may throw.

manager:start(callback)

Loads saved state if needed, obtains missing or expired certificates, installs the active set and enables renewal. Call after configure().

Parameters

• function callback - receives result (table or nil) and err (table or nil). On success, result.started (boolean) indicates whether this call started management rather than finding it already enabled. Preparation can add result.rebuilt (number), result.reused (boolean) and result.cleaned (boolean). A service change instead adds result.switch (table), containing changed and reused (boolean), and rebuilt (number when certificates were rebuilt). Failure is nil, err.

Return values

• boolean or nil result - true when startup is requested, including when already enabled. Missing configuration returns nil, err (table), with code not_configured; a closed manager returns nil, err with code manager_closed. Both errors also go to the callback. Use the callback for completion, which can occur before or after this method returns.

If stop() is called while startup is loading state, that startup cannot later enable renewal. Its callback receives nil, err with code manager_stopped. close() similarly prevents the pending startup, with code manager_closed. Pending storage and installation work is allowed to finish. A subsequent explicit start() can resume a stopped manager.

Throws

Reported storage, issuance and installation failures use the callback. Installer exceptions become certificate_install_failed errors. Completion callback errors are caught and traced. Incorrect configuration or supplied components may raise Lua errors.

manager:stop([callback])

Stops the automatic renewal timer while leaving explicit management methods available. This does not cancel work already in progress, but a pending startup cannot re-enable renewal after this call. Use close() for shutdown.

Parameters

• function callback - Optional. Receives result (boolean) equal to true and err (nil), before this method returns.

Return values

• boolean result - true, including on repeated calls.

Throws

Callback errors are caught and traced. Incorrect use of a supplied timer interface may throw.

manager:switchService(service, options, callback)

Changes the active ACME directory and its account/certificate profile. Switching to the same directory updates the service settings without rebuilding certificates.

Parameters

• table service - ACME service options.
• table or nil options - rebuild (boolean) must be true for a directory change. Pass nil for a same-directory update if no options are needed; keep callback in its third position.
• function callback - receives result (table or nil) and err (table or nil). Success supplies result.changed and result.reused (boolean), plus result.rebuilt (number) when a different profile was prepared. Failure supplies nil, err.

Return values

• boolean or nil accepted - true after a same-directory update or after starting a profile change. Returns nil, err (table) for not_configured or directory_change_requires_rebuild, also sent to the callback. Other early failures may return no values. Use the callback for the outcome; it can run before this method returns.

The manager retains the previous active profile until installation and persistence succeed. If saving the active-profile selection fails after installation, it asks the installer to restore the previous set. An unsuccessful restoration is reported in err.rollback (table). The host's installer determines the effect of partial installation and empty sets.

Throws

Reported preparation, storage and installation failures use the callback. Installer exceptions become certificate_install_failed errors. Callback errors are caught and traced. Incorrect arguments or supplied components may raise Lua errors.

manager:renew(domain, options, callback)

Checks or forces renewal of one managed certificate, then installs the current set.

Parameters

• string domain - exact managed domain name.
• table or nil options - force (boolean) defaults to false. True requests renewal regardless of its scheduled time. Pass nil or an empty table for defaults, keeping callback in the third position.
• function callback - receives result (table or nil) and err (table or nil). Success supplies a copy of the installed certificate record, which can be the existing record if renewal is not due. Failure supplies nil, err.

Return values

• boolean or nil result - true after starting the operation. A missing domain returns nil, err (table), with code certificate_not_found, and also invokes the callback. Busy or closed manager errors go to the callback, with no direct return values. Completion may precede this method's return.

Throws

Reported issuance, persistence and installation failures use the callback. Installer exceptions become certificate_install_failed errors; completion callback errors are caught and traced. Incorrect options or supplied components may raise Lua errors.

manager:revoke(domain, options, callback)

Requests revocation, removes the saved record, persists the profile, and passes the remaining set to the installer. Removing the last record retains the installed certificates when using the built-in installer.

Revocation does not remove the domain from configuration. If the domain remains configured, a later startup can obtain a new certificate because its saved record is now missing. Remove the domain from the host configuration as well if the host should stop managing certificates for that name.

Parameters

• string domain - exact managed domain name.
• table or nil options - reason (number) is an optional ACME revocation reason code. Pass nil or an empty table to omit it, keeping callback in the third position.
• function callback - receives result (boolean or nil) and err (table or nil). Success is true, nil after revocation, persistence and installer completion. Failure is nil, err. A later persistence or installation failure does not undo revocation.

Return values

• boolean or nil result - true after starting the operation. A missing domain returns nil, err (table), with code certificate_not_found, and also invokes the callback. Busy or closed manager errors go to the callback, with no direct return values. Completion may precede this method's return.

Throws

Reported service, storage and installation failures use the callback. Installer exceptions become certificate_install_failed errors; completion callback errors are caught and traced. Incorrect options or supplied components may raise Lua errors.

manager:status()

Returns an operational snapshot without certificate private keys.

Parameters

None.

Return values

• table status - A new snapshot with the fields below.
• boolean status.loaded - Saved state has been loaded; this does not confirm successful installation.
• boolean status.started - Renewal management has been enabled. May be true while startup work is still pending.
• boolean status.closed - close() has been called.
• string or nil status.operation - Active serialized operation, or nil. Initial storage loading is not represented here.
• string or nil status.directoryUrl - Active profile's ACME directory, or nil before a profile is active.
• table status.domains - Keyed by domain name (string). Each value (table) contains expiresAt and renewAt (number or nil, Unix seconds), ariCheckAt (number or nil, Unix seconds), ariId (string or nil), and explanationUrl (string or nil).
• table status.jobs - Array of engine job status tables.
• table or nil status.lastError - Most recent recorded manager error. It is retained after later success; not every rejected call updates it.
• number or nil status.retryAt - Scheduled retry time in Unix seconds, or nil. stop() cancels the timer but does not clear this stored value.

Renewal dates may be more than 49.7 days away. The manager splits long waits into timer intervals of at most 4294967295 milliseconds and checks the due dates again after each interval. An intermediate wakeup does not renew a certificate before its scheduled date.

Throws

No error for a valid manager and supported engine. Errors from a supplied engine's jobs() method propagate.

manager:domains()

Reads managed certificate records, including private keys. Use status() for public diagnostics.

Parameters

None.

Return values

• table certificates - a copy keyed by domain name (string), with certificate record values (table). It is empty before a profile is active. Changes to the copy do not alter manager state.

Throws

Does not throw for valid managed records.

manager:certificate(domain)

Parameters

• string domain - the exact managed domain name.

Return values

• table or nil record - a copy of the certificate record, including its private key. Nil means no matching record exists. This lookup does not normalize the domain.

Throws

Does not throw for a valid domain argument and managed record.

manager:account()

Parameters

None.

Return values

• table or nil account - a copy of the active ACME account, including its private key when present. Nil means no profile is active. Treat the returned account as private administration data.

Throws

Does not throw for a valid managed account.

manager:close([callback])

Stops the renewal timer and closes the engine. Call during shutdown when using the manager directly.

Parameters

• function callback - Optional. Receives result (boolean or nil) and err (table or nil). After engine close completes, it receives true, nil on success or nil, err if the supplied engine reports a close error.

Return values

• boolean or nil result - true when the first close is accepted, acknowledging the request. Repeated calls return no values and invoke the supplied callback immediately with true, nil; they do not wait for an earlier close to finish.

While a certificate installer is pending, returns nil, err (string), where err is "busy". The manager remains open, its timer is unchanged, and the close callback is not called. The caller must retry after installation finishes. No close retry is queued internally.

Throws

Reported engine close failures are passed to the callback. Completion callback errors are caught and traced. Incorrect use of a supplied engine or timer may throw.

domains(), certificate(), and account() return trusted management data that can include private keys. Do not use these values as status or logging data.

Certificate Record

-- Certificate record returned by manager accessors
{
   domain = "device.example.com",
   privateKey = privateKey,
   certificate = pemCertificateChain,
   expiresAt = unixTime,
   renewAt = unixTime,
   ariCheckAt = optionalUnixTime,
   ariId = optionalAriIdentifier,
   explanationUrl = optionalUrl,
   orderUrl = "https://acme.example/order/123",
   directoryUrl = "https://acme.example/directory",
   issuedAt = unixTime
}

• string domain - DNS name used for a public certificate record, or the stable $device label used by SharkCA.
• string or table privateKey - Software private key or TPM key descriptor. Treat it as secret management data.
• string certificate - PEM certificate chain.
• number expiresAt - Certificate expiration as a Unix timestamp in seconds.
• number renewAt - Scheduled renewal time as a Unix timestamp in seconds.
• number ariCheckAt - Optional next ACME Renewal Information check time.
• string ariId - Optional ACME Renewal Information certificate identifier.
• string explanationUrl - Optional provider explanation URL returned with renewal information.
• string orderUrl - ACME order URL that issued the certificate.
• string directoryUrl - ACME directory that owns the order and account.
• number issuedAt - Issuance time as a Unix timestamp in seconds.

The manager uses ACME Renewal Information (ARI) when the service advertises RFC 9773 support. Otherwise, it schedules renewal from the certificate expiration time with a small random offset. Retryable renewal failures back off from 30 seconds to five minutes. A permanent failure is checked again after six hours.

A scheduled check remains busy until certificate installation completes. Installation failure is recorded in status().lastError (table), with code certificate_install_failed, and retried after six hours under the existing non-temporary error policy. The retry installs the saved certificate set; it does not request another certificate unless renewal is due. If renewal or refresh also failed, its error remains primary and lastError.install (table) contains the installation error. A successful retry clears retryAt; lastError remains the most recent recorded failure.

SharkTrust Client

Dns.createClient() creates the low-level SharkTrust device client. It handles device enrollment, authenticated portal commands, DNS updates, and reverse connections. It is not an ACME client and does not persist credentials. Most applications use acme/runtime, which creates this client and the persistent DNS adapter automatically.

Dns.identity(options)

Resolves portal identity without making a network request. createClient() calls this resolver automatically.

Parameters

• table options - Optional. Contains the identity and transport fields accepted by createClient(). Defaults to an empty table.

Return values

• table identityOptions - the original options table if any of portalUrl, zoneKey or proof is supplied. This resolver does not validate or fill in an incomplete explicit identity; createClient() validates it.

Otherwise, returns a copy of options with portalUrl (string, prefixed with https://), zoneKey (hexadecimal string), and proof (function) from the compiled identity module. It first loads etokengen, falling back to tokengen only if that load fails. If neither loads, or the selected module lacks a proof function, returns nil, err (table) with code sharktrust_not_configured. Keep the resulting identity and proof callback private.

Throws

Incorrect option types or an incompatible compiled identity module may throw. Errors raised by the selected module's info() function propagate. Missing compiled identity support is reported as nil, err.

Dns.createClient(options)

Creates a client for one SharkTrust portal and zone. Omit the identity fields, or the entire options table, to use the compiled identity through Dns.identity(). Call it directly only when an application needs low-level SharkTrust operations or when constructing Dns.createSharkTrust() without the runtime.

local Dns = require"acme/dns"
local client, err = Dns.createClient {
   portalUrl = "https://portal.example.com/sharktrust.lsp",
   zoneKey = "<64-hexadecimal-character-zone-key>",
   proof = hostProof, -- host callback described below; no secret option
   credential = savedDeviceCredential,
   http = httpOptions,
   reverse = reverseOptions
}

Parameters

• table options - Optional client settings below. Omit it to resolve the compiled identity.

• string portalUrl - Required for an explicit identity. HTTPS portal root or exact /sharktrust.lsp endpoint. Other paths, queries, fragments, and non-HTTPS URLs are rejected.
• string zoneKey - Required for an explicit identity. Zone key as exactly 64 hexadecimal characters.
• function proof - Required for an explicit identity. proof(message) receives a binary-safe string and must return a 32-byte binary Hash-based Message Authentication Code (HMAC). Use a generated or hardware-backed function when the zone secret should not be exposed to Lua. It is synchronous and must not yield. There is no secret option.
• string credential - Required for authenticated commands after enrollment. Previously saved device credential as exactly 64 hexadecimal characters. The DNS adapter normally restores it with setCredential().
• table http - Optional. BAS HTTP client options, such as a proxy or custom trusted SharkSSL client. Trusted TLS validation is always enabled.
• table reverse - Optional. Options passed to native ba.revcon. The client supplies the portal URL and authentication headers.

The optional reverse table accepts these native reverse-connection settings. The SharkTrust client supplies url and the authentication headers:

• string intf - optional local interface address to bind.
• string proxy - optional proxy server.
• string proxyuser and string proxypass - optional proxy credentials. Supply both together.
• boolean socks - true selects SOCKS proxy mode. The default is false.
• boolean ipv6 - true uses IPv6. The default is false.
• boolean trusted - controls server-certificate validation. The default is true. Do not disable validation in a deployed product.
• userdata shark - optional SharkSSL client object. The default is ba.sharkclient().

Return values

• table client - on success, or nil, err (table) on failure. Identity resolution errors are forwarded. Explicit validation codes include invalid_portal_url, invalid_zone_key, invalid_proof_source and invalid_device_credential. A failing or invalid proof result gives proof_failed. Construction checks the identity proof locally; it does not enroll, open a reverse connection or contact the portal.

Throws

Proof callback errors are caught and reported as proof_failed. Incorrect option types, compiled-identity interfaces or native hashing setup can raise Lua errors.

Host Proof Callback

The host supplies proof(message), a synchronous function accepting the exact binary-safe string to authenticate, including any NUL bytes. It must return a 32-byte binary HMAC-SHA-256 result and must not yield. The client constructs the message and base64url-encodes the result for X-SharkTrust-Proof. Do not change the message or encode the result in the callback. The client neither receives the zone secret nor derives its proof key.

A compiled tokengen.proof or etokengen.proof function can be supplied directly. For host-provisioned secrets, this helper recalculates the key on each call:

-- Capture globals during mako.conf evaluation for later callback calls.
local ba,string,tonumber=ba,string,tonumber
local function makeProof(zoneKey,secret)
   return function(message)
      local salt=zoneKey:gsub("%x%x",function(pair) return string.char(tonumber(pair,16)) end)
      local key=ba.crypto.PBKDF2("sha256",secret:upper(),salt,1000,32)
      return ba.crypto.hash("hmac","sha256",key)(message)(true,"binary")
   end
end

makeProof(zoneKey, secret) is an illustrative host helper, not a client API. Both required arguments are strings of exactly 64 hexadecimal characters, with no defaults. It returns the callback. Assign hostProof=makeProof(zoneKey, zoneSecret), where zoneSecret is the host-provisioned secret string. Capture globals during mako.conf evaluation as shown: its loader removes the global fallback before later callback calls.

The helper uses Password-Based Key Derivation Function 2 (PBKDF2) with HMAC-SHA-256 to derive its proof key. Its password is the secret's 64 uppercase ASCII characters; its salt is the hex-decoded 32-byte zone key. It uses 1000 iterations and produces 32 bytes. Do not hex-decode the secret. The callback then authenticates the unchanged message with HMAC-SHA-256 using that derived key. Recalculating the key uses more CPU than deriving it once; this helper retains only the host-provided credentials between calls.

The host supplies its configuration and callback again on startup. The core does not persist them. Xedge's settings UI retains its own encrypted credential configuration and supplies a callback internally. Portal-issued device credentials and ACME account/certificate state still require persistence.

SharkTrust Client Methods

Use this table to find a method, then follow its link for argument types, return values, and callback behavior.

client:isAvailable(name, callback)

Parameters

• string name - DNS label or full name, 1 through 253 characters.
• function callback - Required. Receives result (table or nil) and err (table or nil). On success it supplies result.available (boolean) and result.name (string), the normalized full name. This check does not reserve the name. Failure is nil, err.

Return values

• boolean or nil accepted - true when work is scheduled. A closed client returns nil, err (table), with code client_closed, and also invokes the callback. Completion may run before this method returns.

Throws

Reported transport, portal and proof failures use the callback. Proof callback errors become proof_failed; completion callback errors are caught and traced. Incorrect arguments or errors raised by supplied/native components may propagate.

client:enroll(request, callback)

Parameters

• table request - enrollment settings.
• function callback - Required. Receives result (table or nil) and err (table or nil). On success it supplies result.deviceId, result.name and result.credential (string). The client retains the lowercase credential; the caller must persist it. The DNS adapter normally performs this operation and persistence together. Failure is nil, err.

Return values

• boolean or nil accepted - true when work is scheduled. A closed client returns nil, err (table), with code client_closed, and also invokes the callback. Completion may run before this method returns.

Throws

Reported transport, portal and proof failures use the callback. Proof callback errors become proof_failed; completion callback errors are caught and traced. Incorrect arguments or errors raised by supplied/native components may propagate.

client:isRegistered(callback)

Parameters

• function callback - Required. Receives result (table or nil) and err (table or nil). On success it supplies result.registered (boolean), with result.deviceId and result.name (string, optional). Before success, the client also discovers its local IPv4 address and reports it to the portal. The callback result includes result.sockname (string), this local address of the connection to the portal. Address discovery or update failure reports an error even if the registration check succeeded. Failure is nil, err.

Return values

• boolean or nil accepted - true when work is scheduled. A closed client returns nil, err (table), with code client_closed, and also invokes the callback. Completion may run before this method returns.

Throws

Reported transport, portal and proof failures use the callback. Proof callback errors become proof_failed; completion callback errors are caught and traced. Incorrect arguments or errors raised by supplied/native components may propagate.

client:setIpAddress(ipAddress, callback)

Parameters

• string ipAddress - new local IPv4 address in dotted-decimal form.
• function callback - Required. Receives result (table or nil) and err (table or nil). On success it supplies the portal acknowledgement table. Call after an address change; startup normally discovers and reports the initial address. Failure is nil, err.

Return values

• boolean or nil accepted - true when work is scheduled. A closed client returns nil, err (table), with code client_closed, and also invokes the callback. Completion may run before this method returns.

Throws

Reported transport, portal and proof failures use the callback. Proof callback errors become proof_failed; completion callback errors are caught and traced. Incorrect arguments or errors raised by supplied/native components may propagate.

client:setAcmeRecord(request, callback)

Parameters

• table request - TXT record settings.
• function callback - Required. Receives result (table or nil) and err (table or nil). On success it supplies the portal acknowledgement table. The DNS adapter calls this during challenge publication. Failure is nil, err.

Return values

• boolean or nil accepted - true when work is scheduled. A closed client returns nil, err (table), with code client_closed, and also invokes the callback. Completion may run before this method returns.

Throws

Reported transport, portal and proof failures use the callback. Proof callback errors become proof_failed; completion callback errors are caught and traced. Incorrect arguments or errors raised by supplied/native components may propagate.

client:removeAcmeRecord(callback)

Parameters

• function callback - Required. Receives result (table or nil) and err (table or nil). On success it supplies the portal acknowledgement table. The DNS adapter calls this during challenge cleanup. Failure is nil, err.

Return values

• boolean or nil accepted - true when work is scheduled. A closed client returns nil, err (table), with code client_closed, and also invokes the callback. Completion may run before this method returns.

Throws

Reported transport, portal and proof failures use the callback. Proof callback errors become proof_failed; completion callback errors are caught and traced. Incorrect arguments or errors raised by supplied/native components may propagate.

client:getWan(callback)

Parameters

• function callback - Required. Receives result (table or nil) and err (table or nil). On success it supplies result.ipAddress (string), the public IPv4 address observed by the portal. Failure is nil, err.

Return values

• boolean or nil accepted - true when work is scheduled. A closed client returns nil, err (table), with code client_closed, and also invokes the callback. Completion may run before this method returns.

Throws

Reported transport, portal and proof failures use the callback. Proof callback errors become proof_failed; completion callback errors are caught and traced. Incorrect arguments or errors raised by supplied/native components may propagate.

client:reverseConnection([enable])

Parameters

• boolean enable - Optional. Defaults to true. False stops the reverse client; true requests a reverse connection using the current credential.

Return values

• boolean or nil result - true after disabling the reverse client or creating and configuring it. This does not confirm a connection; check reverseStatus().

On failure returns nil, err (table). Errors include client_closed, not_enrolled, reverse_connection_unavailable and proof_failed. Except when already closed, the requested enable setting is retained even if startup fails. A later credential update attempts to restart an enabled connection.

Throws

Proof callback errors are converted to proof_failed. Incorrect native reverse-connection options or incompatible supplied components may throw.

client:setCredential(credential)

Parameters

• string or nil credential - a 64-character hexadecimal device credential. Nil clears it and stops the reverse client, retaining the requested enable setting. A string is stored in lowercase. This method does not persist the credential.

Return values

• boolean or nil result - true when the credential is stored or cleared. An invalid credential returns nil, err (table), with code invalid_device_credential, and leaves the existing credential unchanged.

Setting a credential attempts to restart an enabled reverse connection. The true result confirms storage only; a returned restart error is not forwarded. Inspect reverseStatus() for connection state.

Throws

Invalid credential values are reported as nil, err. Errors raised by native options or supplied components during reverse restart may propagate.

client:close([callback])

Clears credential and proof references and closes reverse and HTTP clients.

Parameters

• function callback - Optional. Receives result (boolean) equal to true and err (nil) after active operations finish. Each operation retains its own completion callback and error result; these errors are not aggregated into the close result. The close callback may run before this method returns.

Return values

• boolean result - true, acknowledging shutdown. Repeated calls also return true; their callbacks wait for active operations to finish.

Throws

Completion callback errors are caught and traced. Errors from incorrect use of supplied components may propagate. Return values from underlying transport close methods are not forwarded.

client:reverseStatus()

Parameters

None.

Return values

• table status - A new snapshot with the following fields.
• boolean status.enabled - True when reverse connections were requested. This is not confirmation of an active connection.
• boolean status.connected - True when the native connection status is 202.
• number status.status - Native reverse-connection status, or zero when no reverse client exists.
• number status.connections - Native connection count, or zero when no reverse client exists.

Closing the client stops its reverse connection but does not reset the stored enable setting. Use connected to inspect connection state.

Throws

No error for a valid client using the supported native reverse interface. Errors raised by a custom reverse interface's status() method propagate.

client:credential()

Parameters

None.

Return values

• string or nil credential - the current device credential, stored as 64 lowercase hexadecimal characters. Nil means no credential is set, including after close(). Treat this value as secret. Reading it does not persist it.

Throws

Does not throw for a valid client.

client:identity()

Parameters

None.

Return values

• table identity - a copy containing portalUrl (string), the normalized HTTPS portal endpoint, and zoneIdentity (string), an opaque, non-secret fingerprint. Changing the returned table does not change the client. The identity remains available after close().

Throws

Does not throw for a valid client.

Enrollment and Device Names

client:enroll({
   name = "controller",
   namePolicy = "exact",
   dns = "local",
   info = "Xedge"
}, function(result, err) end)

• string name - Optional. Preferred DNS label or full name in the selected zone. The portal assigns a name when omitted.
• string namePolicy - Optional. exact or increment. An explicit name defaults to exact.
• string dns - Optional. local, wan, or both. The default is local.
• string info - Optional. Device description of at most 256 bytes.

namePolicy="exact" requires the requested name and returns name_unavailable on a conflict. namePolicy="increment" lets the portal try numbered variants such as controller1 and controller2. If a name is supplied without a policy, the policy is exact. If no name is supplied, the portal assigns one.

The normal DNS adapter saves a random enrollment credential before contacting the portal and reuses it after failures or restarts. The updated portal recovers an existing registration by that credential before checking name availability. A different credential requesting an occupied exact name leaves the old device unchanged, triggers an immediate email attempt to the portal log recipient, and keeps the runtime retrying once per hour. Same-credential recovery does not send a conflict email. Deploy the updated portal before this client.

Selecting the Published Address

The dns field selects the ordinary DNS A record for the enrolled device. It does not select HTTP-01 or DNS-01.

both is ordinary multi-address DNS. It is not split-horizon DNS and does not guarantee failover. Publishing wan does not create a NAT, port-forwarding, or firewall rule. Reverse connection is separate and routes public requests through the portal.

Publishing an ACME TXT Record

Application code normally does not call setAcmeRecord() or removeAcmeRecord(). The SharkTrust DNS adapter calls them from its engine-facing present() and cleanup() methods. This request format is documented for developers implementing or testing a custom DNS integration.

client:setAcmeRecord({
   recordName = "_acme-challenge.controller.example.com",
   recordData = "base64url-acme-validation-value",
   dnsResolveTimeoutMs = 30000
}, function(result, err) end)

• string recordName - Required. DNS TXT record name, from 1 through 253 characters.
• string recordData - Required. Base64url validation value, from 1 through 512 characters. Only letters, digits, underscore, and hyphen are accepted.
• number dnsResolveTimeoutMs - Optional. Integer timeout in milliseconds, from 1,000 through 300,000. The DNS adapter calculates this value from its propagation delay.

Module acme/engine

acme/engine is the low-level RFC 8555 client. It communicates with an ACME directory but does not own persistent storage, renewal timers, certificate installation, Mako configuration, Xedge events, or SharkTrust enrollment. Most applications should use acme/runtime. Use the engine directly when implementing a custom manager or challenge workflow.

Engine.create(options)

Creates a low-level ACME client and its serialized certificate-job queue.

local Engine = require"acme/engine"
local engine = Engine.create {
   tpm = tpmInterface,
   now = os.time
}

Parameters

• table options - Optional. Engine settings below; defaults to an empty table.

• table tpm - optional TPM interface for a standalone integration. It supplies trusted signing and key operations. ECC uses it automatically; it is not a per-key selection option.
• function now - optional function that returns the current Unix time in seconds. The default is os.time. This option is mainly useful for deterministic tests.

Mako and Xedge install their platform TPM callbacks before publishing ba.tpm. Those trusted callbacks take precedence over constructor injection.

Return values

• table engine - a new client with an empty certificate-job queue. Construction does not contact the ACME service, generate keys or load the JWT module.

Throws

Incorrect options or dependency types may raise Lua errors. For valid options, construction has no reported operational error return.

Account Object

The account argument used by certificate and revocation operations has this form:

{
   email = "operator@example.com",
   key = accountPrivateKey,
   url = "https://acme.example/acct/123",
   directoryUrl = "https://acme.example/directory"
}

• string email - required non-empty ACME contact email address for public-CA accounts. SharkCA does not use this field.
• string|table key - ACME account private key. Omit it only for a new account; the engine then creates a P-256 key.
• string url - ACME account URL assigned by the service. Omit it for a new account.
• string directoryUrl - directory that owns the registered account. Omit it for a new account. The engine rejects an account belonging to another directory.

The caller must persist the account returned by certificate operations. The manager does this automatically.

Engine Methods

engine:directory(service, callback)

Downloads and validates an ACME directory to inspect provider capabilities.

Parameters

• table service - ACME service options.
• function callback - receives result (table or nil) and err (table or nil). Success supplies result.directory (table) and result.directoryUrl (string). The directory contains newNonce, newAccount, newOrder and revokeCert (HTTPS strings), and may include renewalInfo (HTTPS string) and meta (table). Failure is nil, err.

Return values

• boolean or nil accepted - true when work is scheduled. Closed-engine or invalid-service rejection returns nil, err (table), also sent to the callback. Completion may occur before or after this method returns.

Throws

Reported transport and response errors go to the callback. A directory requiring External Account Binding returns external_account_required. Malformed JSON returns invalid_response; missing or invalid endpoint URLs return invalid_directory. Callback errors are caught and traced. Incorrect arguments or supplied components may raise Lua errors.

engine:terms(service, callback)

Reads the provider's Terms of Service URL before the application accepts the terms.

Parameters

• table service - ACME service options.
• function callback - receives result (table or nil) and err (table or nil). Success supplies result.url (string or nil), the provider's terms URL when present, and result.directoryUrl (string). Failure is nil, err.

Return values

• boolean or nil accepted - true when work is scheduled. Closed-engine or invalid-service rejection returns nil, err (table), also sent to the callback. Completion may occur before or after this method returns.

Throws

Uses the same directory validation and operational error reporting as directory(). Callback errors are caught and traced. Incorrect arguments or supplied components may raise Lua errors.

engine:certificate(service, account, request, callback)

Queues one certificate order and immediately returns a job object. Use it when a custom manager owns account persistence, certificate persistence, installation, and renewal. Normal applications use the runtime or manager.

-- Use the callback for completion and check immediate submission errors.
local job, err = engine:certificate(service, account, {
   domain = "device.example.com",
   acceptTerms = true,
   challenge = challengeAdapter,
   key = {
      type = "ecc",
      curve = "SECP384R1"
   },
   replaces = optionalAriIdentifier,
   timeout = 600,
   dnsResolveTimeout = 30
}, function(result, requestErr) end)

Parameters

• table service - ACME service options.
• table account - ACME account. For a new account, provide at least string email.
• table request - certificate request options:
  • string domain - required DNS name when identifiers is omitted. When identifiers is supplied, this remains the stable certificate-key name and job label; keep it unchanged when an IP address changes.
  • table identifiers - optional non-empty array of identifier tables. Each has required string type ("dns" or "ip") and string value (the DNS name or IPv4 address). The engine sends these identifiers in the order and includes them as typed CSR SANs. The caller supplies validated identifiers authorized for this device. The first value becomes the CSR common name. Without this option, the order requests the single DNS name in domain.
  • boolean acceptTerms - must be true when the account must be registered.
  • table challenge - optional challenge adapter. Omit it for built-in HTTP-01.
  • table key - optional certificate-key settings:
    • string type - ecc (default) or rsa. Omit this member when supplying privateKey.
    • string curve - ECC curve name. The default is SECP384R1.
    • number bits - RSA key size. The default is 2048.
    • string|table privateKey - optional existing software key or TPM key descriptor. When supplied, the engine does not create a certificate key.
  • string replaces - optional ACME Renewal Information identifier for the certificate being replaced.
  • number timeout - optional maximum polling time in seconds. The default is 600.
  • number dnsResolveTimeout - optional DNS propagation timeout in seconds passed to a DNS-01 adapter. The default is 30.
• function callback(result, err) - required completion callback. result (table or nil) and err (table or nil) describe completion. Failure is nil, err. On success, result contains table account, string|table privateKey, string certificate in PEM format, string orderUrl, string directoryUrl, and optional string ariId.

ECC defaults to SECP384R1 and automatically uses the configured TPM interface. RSA defaults to 2048 bits and always uses a software key. New ACME account keys always use P-256.

The engine processes every authorization. An authorization already marked valid skips challenge presentation, triggering and cleanup. Pending authorizations use the selected challenge adapter as before. These low-level options do not by themselves enable SharkCA registration or IP-change replacement in the runtime or certificate manager.

Return values

• table job - returned when accepted. Rejection returns nil, err (table). An invalid service also invokes the callback; a closed engine returns engine_closed without invoking it. A supplied worker can complete the request before this method returns. Account and request settings are copied; the challenge adapter is shared with the caller.

Throws

Invalid submission arguments or worker setup can throw. Errors inside the certificate coroutine are caught and reported as operation_failed; reported operational failures go to the callback. String errors from native key and CSR creation become operation_failed error tables with the original message. Callback errors are caught and traced. Challenge cleanup is attempted on failure when a challenge context exists.

engine:renewalInfo(service, certificate, callback)

Reads ACME Renewal Information (ARI). The manager normally performs this check.

Parameters

• table service - ACME service options.
• string or table certificate - PEM certificate text, or a table containing certificate (string) or a previously calculated ariId (string).
• function callback - receives result (table or nil) and err (table or nil). Failure supplies nil, err. A successful result has the fields below.

• string result.ariId - Certificate identifier used for ARI.
• table result.suggestedWindow - start and end (number), Unix timestamps in seconds; end is later than start.
• string or nil result.explanationUrl - Optional provider explanation URL.
• number result.retryAfter - Seconds until the next check; defaults to 21600.
• string result.directoryUrl - Selected ACME directory.

Return values

• boolean or nil accepted - true when work is scheduled. If the engine is closed or service validation fails, returns nil, err (table) and also invokes the callback. Completion may run before or after this method returns.

Throws

Reported HTTP, certificate and response errors use the callback. Malformed JSON produces invalid_response; a missing or invalid suggested window produces invalid_renewal_info. A provider without ARI returns ari_unavailable. Callback errors are caught and traced. Incorrect arguments or supplied components may raise Lua errors.

engine:revoke(service, account, certificate, options, callback)

Asks the ACME service to revoke a certificate. This method does not remove saved records or change the installed certificates. Normal applications use manager:revoke().

Parameters

• table service - ACME service options.
• table account - registered ACME account belonging to the selected directory, including its signing key and account URL.
• string or table certificate - PEM certificate text, or a record containing certificate (string).
• table or nil options - optional settings. reason (integer, optional) is the ACME revocation reason code sent to the provider. Pass nil to use no settings; the callback remains the fifth argument.
• function callback - receives result (boolean or nil) and err (table or nil). Success is true, nil after the provider accepts revocation, including an HTTP 200 response with an empty body as shown in RFC 8555. Failure is nil, err.

Return values

• boolean or nil accepted - true when work is scheduled. Closed-engine or invalid-service rejection returns nil, err (table), also sent to the callback. Completion may occur before or after this method returns.

Throws

Reported transport, signing and service failures go to the callback. A signing error string becomes a sign_failed error table; a signer's error table is preserved. No signed request is sent after signing fails. An account from a different directory returns account_directory_mismatch; missing PEM certificate data returns invalid_certificate. Callback errors are caught and traced. Incorrect arguments, invalid signing keys or supplied components may raise Lua errors.

engine:prepareAccount(account)

Prepares an account key synchronously without contacting an ACME service. A custom integration can save the key before associating it with an authenticated device.

Parameters

• table account - required caller-owned account table, modified in place. Optional key (string software PEM or table TPM descriptor) must identify an existing P-256 account key. If absent, the method creates a P-256 key using the existing account-key policy and sets account.key. Other members are preserved.

Return values

• string thumbprint - the 43-character unpadded base64url SHA-256 JWK thumbprint. Failure returns nil, err (string or table) from key creation/restoration or public-key lookup.

There is no callback or automatic persistence. Save the updated account before sending its thumbprint to an enrollment service. Restoring the saved account and calling this method again reuses its key. A later certificate operation still returns the service-assigned account URL, which must also be saved.

Throws

Incorrect arguments and exceptions from supplied TPM methods propagate, as with createKey().

engine:createKey(name, options)

Creates a certificate key synchronously for a custom integration. ECC uses the configured TPM interface when available; otherwise it uses a software key. RSA always uses a software key.

Parameters

• string name - stable TPM key name; an existing TPM key is reused when the interface's hasKey() reports it present. Software key creation does not use this name.
• table options - Optional. type (string) is "ecc" (default) or "rsa". curve (string) defaults to "SECP384R1" for ECC. bits (integer) defaults to 2048 for RSA. Software settings follow ba.create.key().

Return values

• string or table key - a software private key in PEM format or a TPM descriptor. The descriptor contains provider (string, "tpm"), name (string), and options (table) with key (string, "ecc") and curve (string). Failure returns nil, err (string or table): software creation errors are forwarded from ba.create.key(); an unsupported options.type returns a table with code "invalid_key_type".

Throws

Invalid software key settings throw as described for ba.create.key(). Errors raised by the supplied TPM interface propagate. This synchronous method does not catch Lua errors or invoke a completion callback.

engine:jobs()

Lists outstanding certificate requests for diagnostics.

Parameters

None.

Return values

• table jobs - a new array of job status tables. The current job appears first, followed by queued jobs in submission order. Finished jobs and standalone directory, terms, renewal-info and revocation operations are not included.

Throws

Does not throw for valid job state.

engine:close([callback])

Cancels queued work, performs required challenge cleanup, closes owned HTTP clients, and prevents new work. Call during shutdown when using the engine directly.

Parameters

• function callback - Optional. Receives result (boolean or nil) and err (table or nil) after pending work finishes. Success is true, nil. If a cancelled job's challenge cleanup fails during shutdown, receives nil and the cleanup error. The original certificate callback still receives its cancellation error with the cleanup error in err.cleanup.

Return values

• boolean result - true, acknowledging shutdown. The callback reports completion and may run before this method returns. Repeated calls wait for pending work and retain the first shutdown cleanup error.

Throws

Challenge cleanup exceptions are converted to error tables. Completion callback errors are caught and traced. Incorrect use of supplied components may throw.

Challenge Adapter Interface

A challenge adapter makes an ACME validation value reachable and removes it afterward. Runtime users normally select the built-in HTTP adapter, the SharkTrust DNS adapter, or the manual DNS adapter. Implement this interface only for another DNS provider or hosting environment.

challenge.type = "dns-01" -- or "http-01"
challenge:present(context, callback)
challenge:cleanup(context, callback)

• string challenge.type - required adapter type: dns-01 or http-01.
• function challenge:present(context, callback) - publishes or serves the validation value. context is the engine-created table shown below. Call callback(true, nil) only when the value is ready for validation, or callback(nil, err) on failure.
• function challenge:cleanup(context, callback) - removes the value created by present(). context is the same engine-created table. Call callback(true, nil) after cleanup or callback(nil, err) on failure.

For DNS-01, context has this form:

{
   domain = "controller.example.com",
   token = "token-from-acme-server",
   keyAuthorization = "token-and-account-thumbprint",
   challengeUrl = "https://acme.example/challenge/123",
   recordName = "_acme-challenge.controller.example.com",
   recordData = "base64url-acme-validation-value",
   dnsResolveTimeoutMs = 30000
}

For HTTP-01, context has this form:

{
   domain = "controller.example.com",
   token = "token-from-acme-server",
   challengeUrl = "https://acme.example/challenge/123",
   tokenPath = "acme-challenge/token-from-acme-server",
   keyAuthorization = "token-and-account-thumbprint"
}

• string domain - Used by: Both. DNS identifier being validated.
• string token - Used by: Both. Challenge token returned by the ACME service.
• string keyAuthorization - Used by: Both. Token combined with the ACME account-key thumbprint.
• string challengeUrl - Used by: Both. HTTPS ACME challenge URL. The adapter normally does not use it.
• string recordName - Used by: DNS-01. DNS TXT record name to publish.
• string recordData - Used by: DNS-01. Base64url TXT record value to publish.
• number dnsResolveTimeoutMs - Used by: DNS-01. DNS resolution timeout in milliseconds.
• string tokenPath - Used by: HTTP-01. Path below /.well-known/ where keyAuthorization must be served.

All context members are supplied by the engine. The adapter must not change them. After a successful present(), the engine calls cleanup() for success, failure, timeout, cancellation, or callback error.

Certificate Job

engine:certificate() returns a job immediately. Use the job only to inspect or cancel a low-level certificate request. Runtime and manager users normally do not handle job objects.

job:id()

Parameters

None.

Return values

• integer id - identifies this job within its engine. Identifiers start at 1 and increase for each accepted certificate request. Separate engines have separate sequences.

Throws

Does not throw for a valid job.

job:status()

Reads progress or the final outcome of a retained job object. Completion is also delivered through the certificate callback.

Parameters

None.

Return values

• table status - A new snapshot with the following fields.
• integer status.id - The job identifier.
• string status.state - queued, running, completed, failed or cancelled.
• string status.domain - Requested certificate domain.
• table or nil status.error - A copy of the final error, or nil. Pending cleanup can leave the job running after cancellation was requested.

Throws

Does not throw for valid job state.

job:cancel([callback])

Cancels a queued or running operation and performs challenge cleanup when required.

Parameters

• function callback - Optional. Receives result (boolean or nil) and err (table or nil). Success is true, nil. Cleanup failure is nil, err. The original certificate callback retains its cancellation error and includes the cleanup failure in err.cleanup. A call on an already finished job immediately reports true, nil without repeating cleanup.

Return values

• boolean result - true, acknowledging cancellation. The callback reports completion and may run before this method returns.

Throws

Challenge cleanup exceptions are converted to error tables. Errors from the certificate and cancellation callbacks are caught and traced.

TPM Interface

The optional TPM interface stores ECC private keys outside Lua and performs signing or certificate-request operations with those keys. A standalone host implements these synchronous functions. Normal Mako and Xedge applications do not provide this table.

local tpmInterface = {
   hasKey = function(name) end,
   createKey = function(name, options) end,
   jwtSign = function(name, payload, protectedHeader) end,
   keyParams = function(name) end,
   createCsr = function(name, distinguishedName,
      certificateTypes, keyUsages) end
}

hasKey(name)

Parameters

• string name - stable TPM key name.

Return values

• boolean exists - true if the key is available, false otherwise.

Throws

Platform exceptions propagate to the calling engine operation.

createKey(name, options)

Parameters

• string name - stable TPM key name.
• table options - contains key (string, "ecc") and curve (string). Creation must make the named key available before returning. hasKey(), when supplied, is checked before creation.

Return values

Ignored by the ACME layer; a direct nil, err return is not recognized as a creation failure.

Throws

Platform exceptions propagate to the calling engine operation.

jwtSign(name, payload, protectedHeader)

Parameters

• string name - key name.
• table or string payload - ACME request data, including an empty string for POST-as-GET.
• table protectedHeader - ACME signing headers.

Return values

• table jws - Signed request table, either the first return value or the second return value after compact (string), matching jwt.sign(). The table contains protected, payload and signature (base64url strings). Failure is nil, err (string or table). The engine preserves an error table or wraps an error string in a sign_failed table.

Throws

Platform exceptions propagate to the calling engine operation.

keyParams(name)

Parameters

• string name - name of the P-256 account key.

Return values

• string x, y - raw binary P-256 public-key coordinates, or nil, err (string or table) on failure.

Throws

Platform exceptions propagate to the calling engine operation.

createCsr(name, distinguishedName, certificateTypes, keyUsages)

Parameters

• string name - certificate key name.
• table distinguishedName - contains commonname (string), the requested domain.
• table certificateTypes - An array of strings containing "SSL_CLIENT" and "SSL_SERVER".
• table keyUsages - an array containing "DIGITAL_SIGNATURE" and "KEY_ENCIPHERMENT".

Return values

• string csr - PEM certificate signing request, or nil, err (string or table) on failure.

Throws

Platform exceptions propagate to the calling engine operation.

Engine.setTPM(tpmInterface)

Parameters

• table tpmInterface - trusted platform functions described above. Reserved for host bootstrap before publishing ba.tpm. Standalone applications normally pass tpm to Engine.create() instead.

Return values

None. Installs the trusted callbacks and removes setTPM from the module, allowing only one installation.

Throws

Incorrect interface types can throw. Calling Engine.setTPM again fails because that function no longer exists. Individual platform callbacks are used and checked later by engine operations.

Certificate jobs catch Lua errors from platform callbacks and report operation_failed. Direct createKey() and standalone revocation do not provide that coroutine error handling; see their method contracts.

HTTPS Trust Settings

The ACME service and SharkTrust or SharkCA portal must present an HTTPS certificate trusted by the device. By default, the shared acme/http module uses ba.sharkclient(). If your portal uses a private CA, configure its trust store before creating the runtime or other clients.

Http.setCertStore(store)

Call require"acme/http".setCertStore(store) to set the shared default for subsequently created ACME HTTP clients.

• userdata, string or nil store - a CA store created by ba.create.certstore(), or a valid binary SharkSslCAList string accepted by ba.create.sharkssl(). Pass nil to restore the default ba.sharkclient() selection. Add all CA certificates before passing a store.

Returns no values. Store validation and construction follow ba.create.sharkssl(), including its Lua errors. The setting is shared across applications using this module; it does not replace HTTP clients that already exist. An explicit http.shark client option takes precedence.

Host Logging

Mako and Xedge log the numeric notification codes and the optional message directly. A custom host may translate them into readable messages in its own notify(code, msg) callback. Use operation callbacks for detailed errors and runtime:status() for non-secret diagnostics.

Persistent State and Upgrades

The manager stores state below acme/ by default. Each effective ACME directory has an independent profile below acme/services/, and acme/active.json selects the installed profile. A Mako SharkTrust integration stores device enrollment separately in acme/sharktrust.json.

The modules read only their current state format. They do not import the old cert/ layout, acme-v2/, legacy devkey or refresh-token state, or account and certificate files from an earlier implementation.

Account keys, certificate private keys, SharkTrust device credentials, zone secrets, and proof material are secrets. Keep the writable I/O private and exclude it from application packages, source repositories, diagnostics, and downloads.

Current Protocol Limits

The normal public-CA runtime requests one DNS identifier per ACME order and manages each entry in domains as a separate certificate record. It does not provide a multi-name certificate through that list.

The SharkCA profile supports a device name, an approved local IPv4 address, or both in one certificate. The low-level engine:certificate() also accepts an explicit identifiers array. The caller must supply validated identifiers and a compatible service and validation flow.

The modules do not implement:

• External Account Binding for ACME providers that require it;
• ACME account key rollover;
• TLS-ALPN-01 validation;
• provider-specific account-management extensions.

SharkCA does not support DNS commands, reverse connections, or RSA keys. Directory changes require closing and recreating its runtime.